🔗 Link Entity to Code Commits | Pull Requests

Overview

This document outlines how to update entities in target work systems by sending requests and code commits to SyncNow DevOps Gate APIs.
For updates to work, developers must mention work system entities in their code commit comments using #{target work system ID}.

You can use provided Groovy scripts for Jenkins or copy cURL commands directly from the DevOps Gate project configuration in the SyncNow UI.

---

🔄 Update Entities from Code Commits with Comment

This process updates entities mentioned in the comments of all commits in a build.

---

💡 Usage Examples

• Update an entity with the build or deploy version number.
• Update an entity if the latest build has failed.
• Link the build to an entity—build details and URL are set in the entity comment.

A typical commit comment might look like:
Done some fixes to code #ENT-1, #ENT-2
After the build, entities ENT-1 and ENT-2 will be updated according to the mapping definition.

---

📨 API Request

Send a POST request to:

POST /api/v1.0/DevOpsGate/Enrich/{DevOpsProjectID}?action=update

Payload Parameters:

Parameter	Description
Param1…ParamX	Parameters as defined in the DevOps Gate per Entity Type mapping
entityUniqueKey	(Optional) Update an entity directly without using comments
comments	The comments with #{Entity ID}

Sample Payload:

[
  {
    "fields": [
      { "key": "Param1", "value": "string" },
      { "key": "Param2", "value": "string" },
      { "key": "Param3", "value": "string" }
    ],
    "comments": "String with entities unique identifiers from the target system to add comments or remote link. For example, this is a comment in some commit. Need to update entities #CLS-3938, #CLS-3933"
  }
]

---

🟢 API Response

Parameter	Description
updatedEntitiesID	List of updated entity IDs and their system IDs
errors	Errors that occurred during the update process
warnings	Warnings that occurred during the update process

Sample Response:

{
  "updatedEntitiesID": [
    {
      "systemID": "10",
      "entityKeys": [
        "CLS-3933",
        "CLS-3938"
      ]
    }
  ],
  "errors": [],
  "warnings": []
}

---

🤖 Jenkins Script Example

This Jenkins script collects all comments with entity IDs mentioned in commits, joins them, and adds them as one comment to be updated in the target system. It then uses the SyncNow DevOps Gateway to update all entities referenced in the commit messages.

@NonCPS
def getCommentsString() {
    def list = []
    def changeLogSets = currentBuild.changeSets
    for (int i = 0; i < changeLogSets.size(); i++) {
        def entries = changeLogSets[i].items
        for (int j = 0; j < entries.length; j++) {
            def entry = entries[j]
            if (entry.msg != null) {
               list.add("""${entry.commitId} on ${new Date(entry.timestamp)}: ${entry.msg.replaceAll("[\n\r]", " ")}""")
            }
        }
    }
    return list.join(',')
}

pipeline {
    agent any
    stages {
        stage('Clone') { steps { echo 'Clone Code' } }
        stage('Version') { steps { echo 'Version' } }
        stage('Test') { steps { echo 'Test' } }
        stage('Build') { steps { echo 'Build' } }
        stage('Publish') { steps { echo 'Publish' } }
        stage('Notify SyncNow') {
            steps {
                echo 'Notify'
                echo "Job Name is ${JOB_NAME}, Build ID is ${env.BUILD_ID}"
                script {
                    def commits = getCommentsString()
                    def payload = """
[
  {
    "fields": [
      { "key": "Param1", "value": "string" },
      { "key": "Param2", "value": "string" },
      { "key": "Param3", "value": "string" }
    ],
    "comments": "${commits}"
  }
]
                    """
                    def response = httpRequest acceptType: 'APPLICATION_JSON', contentType: 'APPLICATION_JSON', httpMode: 'POST', authentication: 'SyncNow', requestBody: "${payload}", url: "https://<SyncNowBaseURL>/api/v1.0/DevOpsGate/Enrich/<DevOpsProjectID>?action=update"
                    println("Status: ${response.status}")
                    println("Content: ${response.content}")
                }
            }
        }
    }
}

---

📝 Step-by-Step Instructions

1. Create a DevOps Gate Process.

2. Add an entity type mapping and set any field mappings to it.

   

3. Create two entities in the target system that should be updated by the DevOps Gate.

   

4. Go to the DevOps Gate Process Configuration and press the "How It Works" link.

   

5. Select "Update Entities from Commits".

6. Copy the cURL command.

   

7. Paste it into a command line, set the entity keys of the entities created earlier, and execute.

8. Entities will be updated according to the mapping definition.

   

---

Tip:
Use clear and consistent entity references in your commit messages to ensure accurate updates in your work systems.
Automate updates from your CI/CD pipeline to keep your work systems in sync with code changes.

---